/*
 * Copyright 2007 Stefan Arentz <http://stefan.arentz.nl>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.sateh.spaces;

/**
 * The Lease interface defines a type of object that is returned to the lease holder and issued by the lease
 * grantor. Particular instances of the Lease type will be created by the grantors of a lease, and returned
 * to the holder of the lease as part of the return value from a call that allocates a leased resource. The
 * call that requests a leased resource will typically include a requested duration for the lease. If the
 * request is for a particular duration, the lease grantor is required to grant a lease of no more than the
 * requested period of time. A lease may be granted for a period of time shorter than that requested.
 */

public interface Lease
{
    public static final long FOREVER = Long.MAX_VALUE;

    /**
     * 
     * @return
     */

    long getTimeToLive();

    /**
     * Returns the absolute time that the lease will expire, represented as milliseconds from the beginning of the
     * epoch, relative to the local clock.
     *
     * @return a long value in milliseconds from the beginning of the epoch relative to the local clock that
     *          represents the absolute time that the lease will expire
     */

    long getExpirationTime();

    /**
     * The second method, cancel, can be used by the lease holder to indicate that it is no longer interested in the
     * resource or information held by the lease. If the leased information or resource could cause a callback to the
     * lease holder (or some other object on behalf of the lease holder), the lease grantor should not issue such a
     * callback after the lease has been cancelled. The overall effect of a cancel call is the same as lease
     * expiration, but instead of happening at the end of a pre-agreed duration, it happens immediately. If the lease
     * being cancelled is unknown to the lease grantor, an UnknownLeaseException is thrown. The method can also throw
     * a RemoteException if the implementation of the method requires calling a remote object that is the lease holder.
     *
     * @throws UnknownLeaseException
     */

    void cancel() throws UnknownLeaseException;

    /**
     * Renew a lease for an additional period of time. The length of the desired renewal is given, in milliseconds, in
     * the parameter to the call. This duration is not added to the original lease, but is used to determine a new
     * expiration time for the existing lease.
     *
     * @param duration
     * @throws LeaseDeniedException
     * @throws UnknownLeaseException
     */

    void renew(long duration) throws LeaseDeniedException, UnknownLeaseException;
}
